tutorials-and-examples/how-tos/Adding Hunting Bookmarks.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "source": [
        "# How To: Adding Hunting Bookmarks from Notebooks\n",
        "\n",
        "__Notebook Version:__ 1.0<br>\n",
        "__Python Version:__ Python 3.8 - AzureML<br>\n",
        "__Platforms Supported:__<br>\n",
        "    -  Azure ML\n",
        "__Data Source Required:__<br>\n",
        "    -  no\n",
        "    \n",
        "### Description\n",
        "The sample notebook shows how to add hunting bookmarks to Microsoft Sentinel through Jupyter notebooks."
      ],
      "metadata": {}
    },
    {
      "cell_type": "code",
      "source": [
        "# Parameters for notebooks testing, can be ignored safely\r\n",
        "test_run = False"
      ],
      "outputs": [],
      "execution_count": null,
      "metadata": {
        "collapsed": true,
        "jupyter": {
          "source_hidden": false,
          "outputs_hidden": false
        },
        "nteract": {
          "transient": {
            "deleting": false
          }
        },
        "gather": {
          "logged": 1619122065407
        }
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Loading Python libraries\n",
        "from azure.common.credentials import get_azure_cli_credentials\n",
        "import requests\n",
        "import json\n",
        "import uuid\n",
        "import pandas"
      ],
      "outputs": [],
      "execution_count": null,
      "metadata": {
        "trusted": true,
        "gather": {
          "logged": 1619122066467
        }
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Functions will be used in this notebook\r\n",
        "def read_config_values(file_path):\r\n",
        "    \"This loads pre-generated parameters for Microsoft Sentinel Workspace\"\r\n",
        "    with open(file_path) as json_file:\r\n",
        "        if json_file:\r\n",
        "            json_config = json.load(json_file)\r\n",
        "            return (json_config[\"tenant_id\"],\r\n",
        "                    json_config[\"subscription_id\"],\r\n",
        "                    json_config[\"resource_group\"],\r\n",
        "                    json_config[\"workspace_id\"],\r\n",
        "                    json_config[\"workspace_name\"])\r\n",
        "    return None\r\n",
        "\r\n",
        "# Calling Microsoft Sentinel API, the same template can be used for calling other Azure REST APIs with different parameters.\r\n",
        "# For different environments, such as national clouds, you may need to use different root_url, please contact with your admins.\r\n",
        "# It can be ---.azure.us, ---.azure.microsoft.scloud, ---.azure.eaglex.ic.gov, etc.\r\n",
        "def call_azure_rest_api(token, resource_name, request_body, bookmark_id, api_version):\r\n",
        "    \"Calling Microsoft Sentinel REST API\"\r\n",
        "    headers = {\"Authorization\": token, \"content-type\":\"application/json\" }\r\n",
        "    provider_name = \"Microsoft.OperationalInsights\"\r\n",
        "    provider2_name = \"Microsoft.SecurityInsights\"\r\n",
        "    target_resource_name = resource_name\r\n",
        "    api_version = api_version\r\n",
        "    root_url = \"https://management.azure.com\"\r\n",
        "    arm_rest_url_template = \"{0}/subscriptions/{1}/resourceGroups/{2}/providers/{3}/workspaces/{4}/providers/{5}/{6}/{7}?api-version={8}\"\r\n",
        "    arm_rest_url = arm_rest_url_template.format(root_url, subscription_id, resource_group, provider_name, workspace_name, provider2_name, target_resource_name, bookmark_id, api_version)\r\n",
        "    print(arm_rest_url)\r\n",
        "    response = requests.put(arm_rest_url, headers=headers, data=request_body)\r\n",
        "    return response\r\n",
        "\r\n",
        "def display_result_name(response):\r\n",
        "    \"Default to display column - name, you may change it to other columns\"\r\n",
        "    column_name = \"name\"\r\n",
        "    if response != None:\r\n",
        "        entries = [item[column_name] for item in response.json()[\"value\"]] \r\n",
        "        display(entries)\r\n",
        "\r\n",
        "def display_result(response):\r\n",
        "    \"Display the result set as pandas.DataFrame\"\r\n",
        "    if response != None:\r\n",
        "        df = pandas.DataFrame(response.json()[\"value\"])\r\n",
        "        display(df)"
      ],
      "outputs": [],
      "execution_count": null,
      "metadata": {
        "collapsed": true,
        "jupyter": {
          "source_hidden": false,
          "outputs_hidden": false
        },
        "nteract": {
          "transient": {
            "deleting": false
          }
        },
        "gather": {
          "logged": 1619122067789
        }
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Calling the above function to populate Microsoft Sentinel workspace parameters\r\n",
        "# The file, config.json, was generated by the system, however, you may modify the values, or manually set the variables\r\n",
        "tenant_id, subscription_id, resource_group, workspace_id, workspace_name = read_config_values('config.json');"
      ],
      "outputs": [],
      "execution_count": null,
      "metadata": {
        "collapsed": true,
        "jupyter": {
          "source_hidden": false,
          "outputs_hidden": false
        },
        "nteract": {
          "transient": {
            "deleting": false
          }
        },
        "gather": {
          "logged": 1619122070125
        }
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Azure CLI is used to get device code to login into Azure, you need to copy the code and open the DeviceLogin site.\r\n",
        "# You may add [--tenant $tenant_id] to the command\r\n",
        "if test_run == False:\r\n",
        "    !az login --tenant $tenant_id --use-device-code"
      ],
      "outputs": [],
      "execution_count": null,
      "metadata": {
        "collapsed": true,
        "jupyter": {
          "source_hidden": false,
          "outputs_hidden": false
        },
        "nteract": {
          "transient": {
            "deleting": false
          }
        },
        "gather": {
          "logged": 1619122091167
        }
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Extract access token, which will be used to access Microsoft Sentinel Watchlist API for your Watchlist data.  \r\n",
        "credentials, sub_id = get_azure_cli_credentials()\r\n",
        "creds = credentials._get_cred(resource=None)\r\n",
        "token = creds._token_retriever()[2]\r\n",
        "access_token = token['accessToken']\r\n",
        "header_token_value = \"Bearer {}\".format(access_token)"
      ],
      "outputs": [],
      "execution_count": null,
      "metadata": {
        "collapsed": true,
        "jupyter": {
          "source_hidden": false,
          "outputs_hidden": false
        },
        "nteract": {
          "transient": {
            "deleting": false
          }
        },
        "gather": {
          "logged": 1619130034528
        }
      }
    },
    {
      "cell_type": "code",
      "source": [
        "name = \"Bookmark test from notebook\"\r\n",
        "query = \"AzureActivity | where TimeGenerated < ago(5d)\"\r\n",
        "entity_mappings = {}\r\n",
        "entity_mappings.update({'550a6d02-d667-49d8-969a-e709cce03293': 'Account'})\r\n",
        "entity_mappings.update({'201.12.34.111': 'Host'})\r\n",
        "entities = r\"{\\\"550a6d02-d667-49d8-969a-e709cce03293\\\": \\\"Account\\\", \\\"201.12.34.111\\\": \\\"Host\\\"}\"\r\n",
        "query_result = r\"{\\\"Value\\\":0,\\\"Time\\\":\\\"2020-03-22T16:46:20.006499Z\\\",\\\"Legend\\\":\\\"F5Telemetry_LTM_CL\\\",\\\"__entityMapping\\\":\" + entities + \"}\"\r\n",
        "payload_data = \"{\\\"properties\\\": { \\\"displayName\\\": \\\"\" + name + \"\\\", \\\"notes\\\": \\\"Testing from notebook\\\", \\\"labels\\\": [\\\"test\\\"], \\\"query\\\": \\\"\" + query + \"\\\", \\\"queryResult\\\": \\\"\" + query_result + \"\\\" }}\""
      ],
      "outputs": [],
      "execution_count": null,
      "metadata": {
        "collapsed": true,
        "jupyter": {
          "source_hidden": false,
          "outputs_hidden": false
        },
        "nteract": {
          "transient": {
            "deleting": false
          }
        },
        "gather": {
          "logged": 1619130035411
        }
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# Calling Microsoft Sentinel Watchlist API\r\n",
        "response_bookmark = call_azure_rest_api(header_token_value, \"bookmarks\", payload_data, str(uuid.uuid4()), \"2020-01-01\")"
      ],
      "outputs": [],
      "execution_count": null,
      "metadata": {
        "collapsed": true,
        "jupyter": {
          "source_hidden": false,
          "outputs_hidden": false
        },
        "nteract": {
          "transient": {
            "deleting": false
          }
        },
        "gather": {
          "logged": 1619129877775
        }
      }
    },
    {
      "cell_type": "code",
      "source": [
        "response_bookmark.text"
      ],
      "outputs": [],
      "execution_count": null,
      "metadata": {
        "collapsed": true,
        "jupyter": {
          "source_hidden": false,
          "outputs_hidden": false
        },
        "nteract": {
          "transient": {
            "deleting": false
          }
        },
        "gather": {
          "logged": 1619130037840
        }
      }
    }
  ],
  "metadata": {
    "hide_input": false,
    "kernelspec": {
      "name": "python38-azureml",
      "language": "python",
      "display_name": "Python 3.8 - AzureML"
    },
    "language_info": {
      "name": "python",
      "version": "3.8.1",
      "mimetype": "text/x-python",
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "pygments_lexer": "ipython3",
      "nbconvert_exporter": "python",
      "file_extension": ".py"
    },
    "toc": {
      "toc_position": {},
      "skip_h1_title": false,
      "number_sections": false,
      "title_cell": "Table of Contents",
      "toc_window_display": false,
      "base_numbering": 1,
      "toc_section_display": true,
      "title_sidebar": "Contents",
      "toc_cell": false,
      "nav_menu": {},
      "sideBar": true
    },
    "varInspector": {
      "cols": {
        "lenName": 16,
        "lenType": 16,
        "lenVar": 40
      },
      "kernels_config": {
        "python": {
          "delete_cmd_postfix": "",
          "delete_cmd_prefix": "del ",
          "library": "var_list.py",
          "varRefreshCmd": "print(var_dic_list())"
        },
        "r": {
          "delete_cmd_postfix": ") ",
          "delete_cmd_prefix": "rm(",
          "library": "var_list.r",
          "varRefreshCmd": "cat(var_dic_list()) "
        }
      },
      "types_to_exclude": [
        "module",
        "function",
        "builtin_function_or_method",
        "instance",
        "_Feature"
      ],
      "window_display": false
    },
    "kernel_info": {
      "name": "python38-azureml"
    },
    "nteract": {
      "version": "nteract-front-end@1.0.0"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 1
}